Skip to content
lab components / Actions and controls

Pill

Pills are used for labeling, filtering, or user input. They can be static (read-only) or interactive.

ExamplesPropertiesGuidelines
import { Pill } from "@siteimprove/fancylib";

#Examples

#Static

This is the default appearance of the Pill component. Its variant prop is by default set to "static".

Static

<Pill variant={{ type: "static" }}>Static</Pill>

#Interactive

This is the interactive appearance of the Pill component. It has a required onClick prop used to handle the click event and an optional srOnlyText prop used to provide additional text for screen readers. The srOnlyText is for example used by the ActiveFilters function of the Filters component for individual Pill filters, but not for the "Clear all" Pill.

Pills can be user-generated content (e.g., tags). If so, consider:

  • Search Function: Allow searching content by tags.
  • Tag Formatting: Make tags clickable links for filtering or searching.
  • Related Tags: Show related tags to aid discovery.

The action icon for the interative Pill must have the same size as the Pill itself. Since the default size for the Pill is "medium" and the default size for an Icon is "large", in this example the size of the Icon has been set to "medium" as well.

<Pill variant={{ type: "interactive", onClick: () => {}, srOnlyText: "click to remove" }}> Interactive <Icon size="medium"> <IconClose /> </Icon> </Pill>

#Size

The default size of the Pill component is "medium", but can also be set to "small" or "large".

  • Medium: The default size.
  • Small: For compact spaces or secondary labels.
  • Large: For greater emphasis or primary labels.

Small

Medium

Large

<Content gap="small"> <Pill variant={{ type: "static" }} size="small"> Small </Pill> <Pill variant={{ type: "static" }} size="medium"> Medium </Pill> <Pill variant={{ type: "static" }} size="large"> Large </Pill> </Content>

#Icon

To add an icon to a Pill, place an Icon component inside the Pill component. You must specify the correct size for the Icon component so it matches the size of the Pill component, as shown in the example below.

  • Placement:
    • Leading icons: Placed before the label, used for descriptive purposes (not interaction cues).
    • Trailing icons: Placed after the label, typically used for actions (e.g., removal)
  • Usage
    • Use icons to enhance clarity and meaning.
    • Choose icons that align with your design system. Visit the Icons Overview page for an overview of all available Fancy icons.
  • Sizing: Ensure icons match the size of the Pill for visual consistency.

Small

Medium

Large

<Content gap="small"> <Pill variant={{ type: "static" }} size="small"> <Icon size="small"> <IconUser /> </Icon> Small </Pill> <Pill variant={{ type: "static" }} size="medium"> <Icon size="medium"> <IconUser /> </Icon> Medium </Pill> <Pill variant={{ type: "static" }} size="large"> <Icon size="large"> <IconUser /> </Icon> Large </Pill> </Content> <Content gap="small"> <Pill variant={{ type: "interactive", onClick: () => {}, srOnlyText: "click to remove" }} size="small" > Small <Icon size="small"> <IconClose /> </Icon> </Pill> <Pill variant={{ type: "interactive", onClick: () => {}, srOnlyText: "click to remove" }} size="medium" > Medium <Icon size="medium"> <IconClose /> </Icon> </Pill> <Pill variant={{ type: "interactive", onClick: () => {}, srOnlyText: "click to remove" }} size="large" > Large <Icon size="large"> <IconClose /> </Icon> </Pill> </Content>

#Properties

Static

PropertyDescriptionDefinedValue
variantRequired
object
childrenOptional
| string | number | object | element | object
sizeOptional
"large" | "medium" | "small"
data-observe-keyOptional
stringUnique string, used by external script e.g. for event tracking
classNameOptional
stringCustom className that's applied to the outermost element (only intended for special cases)
styleOptional
objectStyle object to apply custom inline styles (only intended for special cases)

#Guidelines

#Best practices

#General

Use Pill when

  • Showing and labeling selectable inputs (removable).
  • Communicating labels, selections, and categories in a concise way.
  • Inputting complex data in a compact form field. (e.g Create a tag in Select)

#Placement

Pill is typically used in the following places:

#Style

  • Siteimprove Design System: Adhere to Siteimprove's guidelines for color, typography, and spacing. If you are not using a component from Fancy, match the styling of yourPill to existing components for visual consistency.
  • Use standard Fancy icons.

#Do not use when

  • Showing static status. Use Badgeinstead.
  • Single action. Use Button for actions that affect other elements.
  • Simple standalone labels: Use plain Inline text or Heading instead.
  • Extensive content: Use Paragraph instead.
  • Highlight inline text. Use Text Highlight instead.

#Accessibility

For designers

  • Ensure sufficient contrast between pill background and text.

For developers

This component comes with built-in accessibility, no extra work required.

Explore detailed guidelines for this component: Accessibility Specifications

#Writing

  • Keep labels short and clear.